---
section: 99-Packages
order: 2
name: webpack-loader
---

# @compiled/webpack-loader

import { Lozenge, HorizontalStack } from '@compiled/website-ui';

<HorizontalStack gap={0.5} spacing={2}>
  <Lozenge>Webpack 4</Lozenge>
  <Lozenge>Webpack 5</Lozenge>
</HorizontalStack>

[Webpack](https://webpack.js.org/) loader used to transform your code.
See [installation](/installation#webpack) for setup instructions.

```bash
npm install @compiled/webpack-loader --save-dev
```

## Options

Configure in your Webpack config.

```js
// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: [
          { loader: 'babel-loader' },
          {
            loader: '@compiled/webpack-loader',
            options: {
              importReact: true,
            },
          },
        ],
      },
    ],
  },
};
```

### Options used by `@compiled/webpack-loader`

`@compiled/webpack-loader` accepts the following options:

- `bake`
- `extensions`
- `extract`
- `extractStylesToDirectory`
- `parserBabelPlugins`
- `resolve`
- `ssr`
- `transformerBabelPlugins`

#### bake

Turns on `@compiled/babel-plugin`.

- Type: `boolean`
- Default: `true`

#### extensions

Extensions that we should consider to be code. We use these to identify if a file should be parsed.

If set, the value of `extensions` will be used in two places:

1. If `resolver` is not set, then `extensions` will be passed to the default resolver, `enhanced-resolver`.
2. This is also passed to `@compiled/babel-plugin` under the hood.

- Type: `string[]`
- Default: none, but note that `enhanced-resolver` and `@compiled/babel-plugin` have their own different defaults when the `extensions` option is not set.

#### extract

Enables extracting all styles to an atomic style sheet. This enables `@compiled/babel-plugin-strip-runtime` under the hood.

You should use this in conjunction with `CompiledExtractPlugin`. Read the [Webpack CSS extraction](/css-extraction-webpack) guide for help.

- Type: `boolean`
- Default: `false`

#### extractStylesToDirectory

When set, extracts styles to an external CSS file. Read [babel-plugin-strip-runtime](/pkg-babel-plugin-strip-runtime) for more information.

- Type: `{ source: string; dest: string }`
- Default: `undefined`

#### parserBabelPlugins

Babel parser plugins to be used when parsing the source code. Define these to enable extra babel parsers (for example, typescript).
See the [babel docs](https://babeljs.io/docs/en/plugins/#syntax-plugins) for more context.

Example usage:

```js
// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: [
          { loader: 'babel-loader' },
          {
            loader: '@compiled/webpack-loader',
            options: {
              parserBabelPlugins: ['typescript'],
            },
          },
        ],
      },
    ],
  },
};
```

This is also passed to `@compiled/babel-plugin` under the hood.

- Type: `ParserPlugin[]`
- Default: `['typescript', 'jsx']`

#### \[Deprecated\] resolve

If `resolver` is not provided, `resolve` specifies options that should be passed to the default resolver (`enhanced-resolver`). The resolver is used to statically evaluate import declarations.

This has been superseded by `resolver`; you should use that instead!

Example usage:

```json
options: {
  // ...
  "resolve": {
    "mainFields": ["module:es2019", "browser", "module", "main"]
  }
}
```

See [enhanced-resolver docs](https://github.com/webpack/enhanced-resolve#resolver-options) for more options.

- Type: `ResolveOptions`
- Default: `undefined`

#### ssr

To be used in conjunction with `extract: true` when having a different configuration for SSR.

When set to true, `ssr` will prevent additional require (one import per rule) in the bundle during style sheet extraction.

This is equivalent to setting `compiledRequireExclude` in `@compiled/babel-plugin-strip-runtime`.

- Type: `boolean`
- Default: `false`

#### transformerBabelPlugins

Babel transformer plugins to be applied to transformed files before the Compiled evaluation.

Use this if you have some sort of babel plugin that should run before Compiled,
likely because you have some sort of non-standard syntax in your code.
See the [babel docs](https://babeljs.io/docs/en/plugins/#transform-plugins) for more context.

Example usage:

```js
// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: [
          { loader: 'babel-loader' },
          {
            loader: '@compiled/webpack-loader',
            options: {
              transformerBabelPlugins: [
                [
                  '@babel/plugin-proposal-decorators',
                  {
                    legacy: true,
                  },
                ],
              ],
            },
          },
        ],
      },
    ],
  },
};
```

- Type: `PluginItem[]`
- Default: `[]`

### Options passed to `@compiled/babel-plugin`

`@compiled/webpack-loader` also accepts the following options. These are not used in the loader itself, but instead they are passed directly to the underlying `@compiled/babel-plugin`.

- `addComponentName`
- `classHashPrefix`
- `classNameCompressionMap`
- `importReact`
- `importSources`
- `nonce`
- `optimizeCss`
- `resolver`

To avoid repetition, we have not included the descriptions here. Please refer to the [`@compiled/babel-plugin` documentation](/pkg-babel-plugin) for more information.

## CompiledExtractPlugin

Plugin to be used when the `extract` option is set to `true`.

```js
// webpack.config.js
const { CompiledExtractPlugin } = require('@compiled/webpack-loader');

module.exports = {
  plugins: [new CompiledExtractPlugin()],
};
```

### Options

#### nodeModulesTest

As a performance optimization you can test paths to include by [passing a webpack condition](https://webpack.js.org/configuration/module/#condition) to the plugin.

```js
new CompiledExtractPlugin({
  nodeModulesTest: /@atlaskit/,
});
```

- Type: `Condition`
- Default: `undefined`

#### nodeModulesInclude

As a performance optimization you can include paths by [passing a webpack condition](https://webpack.js.org/configuration/module/#condition) to the plugin.

```js
new CompiledExtractPlugin({
  nodeModulesInclude: [require.resolve('@atlaskit/button')],
});
```

- Type: `Condition`
- Default: `undefined`

#### nodeModulesExclude

As a performance optimization you can exclude paths by [passing a webpack condition](https://webpack.js.org/configuration/module/#condition) to the plugin.

```js
new CompiledExtractPlugin({
  nodeModulesExclude: [require.resolve('@atlaskit/button')],
});
```

- Type: `Condition`
- Default: `undefined`

#### cacheGroupExclude: boolean

To be used in conjunction with `extract: true` when having a different configuration for SSR.
This will prevent the additional `cacheGroup` chunk to be created during style sheet extraction; compiled-css files should be only generated in the client-side.

```js
new CompiledExtractPlugin({
  cacheGroupExclude: true,
});
```

- Type: `boolean`
- Default: `undefined`

#### sortAtRules

Whether to sort at-rules, including media queries.

See [here](/media-queries-and-other-at-rules) for more information.

- Type: `boolean`
- Default: `true`

#### sortShorthand

Whether to sort shorthand properties so that they always some before longhand properties.

For example, `border` will always come before `borderColor`, which will always come before `borderTopColor`.

See [Shorthand properties](/shorthand) for more information.

```js
new CompiledExtractPlugin({
  sortShorthand: false,
});
```

- Type: `boolean`
- Default: `true`
